home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 25 / Cream of the Crop 25.iso / utility / bfind704.zip / BFIND.DOC next >
Text File  |  1997-04-28  |  19KB  |  424 lines
  1. BFIND.DOC                              1                           Apr 28, 1997
  2.  
  3. The BFIND.EXE program adds Boolean logic to DOS's FIND command.  In most  ways,
  4. it's identical to the FIND command except:
  5.  
  6.   * Adds AND, OR, NOT, and XOR options to  searches  (finding  all  lines  with
  7.     "Apples" or "Bananas", for example).
  8.   * Allows you to specify the starting column of the desired string.
  9.   * Adds a pause (/P) option to have the output pause every 24 lines.
  10.   * Avoids need to include the search string in quotation marks so you can  use
  11.     the program more easily in batch commands.
  12.   * The input file specification can  include  standard  DOS  wildcards  or  an
  13.     external file (@listfile) containing the files to be processed, e.g:
  14.           BFIND /I "SOUND" *.DOC > TEMP.X
  15.   * Allows you to skip the by-file heading information ("----- filename").
  16.   * Can avoid showing file name header if no hits in the file (/-EMPTY option).
  17.   * Handles DOS text files (lines end with CR/LF), Mac text  files  (lines  end
  18.     with CR), or Unix text files (lines end with LF).
  19.   * Should be able to handle input files with line lengths of  5000  characters
  20.     or more.  Should skip the remainder, allowing you to use the wildcards more
  21.     easily.
  22.   * Allows you to remove non-text characters from the output  or  even  specify
  23.     your own character-translation file for them.
  24.   * Pressing escape stops the program early.
  25.  
  26. The only FIND feature that BFIND does *not* support is the ability  to  specify
  27. multilple single input files  without  using  wildcards  ("FIND  ...  BRUCE.TXT
  28. BRUCE.DOC" works--"BFIND ... BRUCE.TXT BRUCE.DOC" does not).  In addition,  you
  29. cannot do piping into BFIND (for example: DIR | BFIND ...).
  30.  
  31. The DOS FIND command allows you to find lines in a text file  which  contain  a
  32. given string.  You can also have the program tell you how many  lines  met  the
  33. search criteria without actually viewing them which is an ideal way to find out
  34. how many times a given string appears in your file.  You can even use  FIND  to
  35. tell you how many total lines are in a given file just by requesting  a  string
  36. that you know will never appear in your file like  "#X$S$"  and  using  the  /C
  37. (count) parameter.
  38.  
  39. BFIND adds to these capabilities.  It gives you the power of AND, OR, NOT,  and
  40. XOR, allowing you to find any line, for example, that  contains  both  "Apples"
  41. and "Oranges" or to  present  any  lines  that  contain  either  "Bananas"  and
  42. "Pears".  In addition, you can do column-specific searching, finding only those
  43. lines, say, that contain "PRINT" beginning in column 10.
  44.  
  45. BFIND allows you to specify wildcards for the input file.  You can also put the
  46. list of file names to process in a text file and  tell  BFIND  to  process  the
  47. files listed therein.
  48.  
  49.  
  50.  
  51. BFIND.DOC                              2                           Apr 28, 1997
  52.  
  53. Defining Character-Translations (The Filter Table):
  54.  
  55. BFIND allows you to translate specified characters as the text is  read.   This
  56. is useful on output, when, for example, the text might contain things like page
  57. eject characters and you are rerouting the output to a printer; the page  eject
  58. characters would, of course, cause lots of extra pages to be printed.
  59.  
  60. There is a default character-translation table built into the program which you
  61. can request  by  passing  in  the  parameter  "/FILTER".   In  this  case,  all
  62. characters between decimal 32 and 126 as well as decimal 9 (the tab) keep their
  63. original values and everything else get translated as a space.  This leaves you
  64. with the following characters:
  65.  
  66.         (tab) (space)                   !"#$%&'()*+,-./
  67.         0123456789                      :;<=>?@
  68.         ABCDEFGHIJKLMNOPQRSTUVWXYZ      [\]^_`
  69.         abcdefghijklmnopqrstuvwxyz      {|}~
  70.  
  71. Alternatively, you can create your own filter file and invoke it by  specifying
  72. the "/FILTER=filename" parameter.  The filters can be in  your  standard  *.INI
  73. file (for example, BFIND.INI) if desired.  If it becomes  large,  however,  you
  74. might want to move it to its own filename.
  75.  
  76. The filter table is an ASCII text file which consists of a series of  lines  in
  77. the following format:
  78.  
  79.         inchar = outchar
  80.  
  81. where "inchar" is the character to change from and "outstr" is what  to  change
  82. the character to.  Both portions can consist of regular  non-space  ASCII  text
  83. characters (like "A" or "z") as well as hexadecimal values (in the  form  &Hxx)
  84. or decimal values (in the form  \nnn).   Both  sides  can  reference  a  single
  85. character  (exactly  one  character  is  always  translated  into  exactly  one
  86. character).  You cannot use a  space  or  equal  sign  in  either  "inchar"  or
  87. "outchar"; use the hexadecimal or decimal representations instead.   The  table
  88. does not have to be in any specified order.  Lines can end with  "/*"  followed
  89. by a comment if you want.
  90.  
  91. Hexadecimal and decimal equivalents are explained in BRUCEHEX.DOC.
  92.  
  93. Examples:
  94.  
  95.         a    = A   /* Translate lowercase "a" into capital "A"
  96.         \032 = _   /* Translate space (decimal 032, &H20 too) into underscore
  97.         \027 = \032    /* Translate escape character to a space
  98.  
  99. Some leading characters  in  INI  files  are  treated  specially  within  Wayne
  100. Software programs.  INI lines that begin with any of the  following  characters
  101. may lead to odd results:  "[", "/", "&", "\", ";", ":", "<", and ",".  To avoid
  102. problems, use hexadecimal or decimal representations for these characters.  For
  103. example, use \047 or &H2F if you want to override the definition of "/".
  104.  
  105.  
  106. BFIND.DOC                              3                           Apr 28, 1997
  107.  
  108. Specifying parameters:
  109.  
  110. Parameters for this program can be set in the following ways.  The last setting
  111. encountered always wins:
  112.   - Read from an *.INI file (see BRUCEINI.DOC file),
  113.   - Through the use of an environmental variable (SET BFIND=whatever), or
  114.   - From the command line (see "Syntax" below)
  115.  
  116.  
  117. Syntax:
  118.  
  119.     BFIND [ /V | /-V ] [ /C | /-C ] [ /N | /-N ] [ /I | /-I ] [ /P | /-P ]
  120.       [ /-HEADER ] [ /-EMPTY ] [ /FILTER | /FILTER=filename ]
  121.       [ /LINES { line1-line2 | line1 linect } ... ]
  122.       [ /ATTR=attribs ] [ /S ] [ /W | /W0 | /-W ]
  123.       [ /MONO ] [ /Iinitfile | /INULL ] [ /-ENV ] [ /? ] [ /?&H ]
  124.       { search } { filespec | @listfile } [ >filename ]
  125.  
  126. where:
  127.  
  128. "/V" says to find those items that do NOT match the  specification.   Initially
  129. defaults to "/-V".
  130.  
  131. "/-V" says to find those items  that  DO  match  the  specification.   This  is
  132. initially the default.
  133.  
  134. "/C" says to show the count of the items found (no individual lines). Initially
  135. defaults to "/-C".  One use for the "/C" parameter is to count  the  number  of
  136. lines in a file; search for all lines that do  *not*  (/V)  contain  a  totally
  137. improbable string and then tally them.  For example:
  138.  
  139.         BFIND /V /C "&^&^&#" MYFILE.TXT
  140.  
  141. "/-C" says to skip counting the items.  This is initially the default.
  142.  
  143. "/N" says to number the output lines.  Initially defaults to "/-N".
  144.  
  145. "/-N" says to skip numbering the output lines.  This is initially the default.
  146.  
  147. "/I" says to make it a case-insensitive search.  So a search for  "Apple"  will
  148. find "APPLE", "apple", ApPle", etc.
  149.  
  150. "/-I" is the opposite of /I and is typically the default.  A search for "Apple"
  151. will not find "APPLE".
  152.  
  153. "/P" says to have the display pause every  24  lines.   Initially  defaults  to
  154. "/-P".
  155.  
  156. "/-P" says to not bother pausing the output display.   This  is  initially  the
  157. default.
  158.  
  159.  
  160. BFIND.DOC                              4                           Apr 28, 1997
  161.  
  162. "/-HEADER" says to skip the normal -----infile output line that appears  before
  163. the results of the output.
  164.  
  165. "/HEADER" says to include the headers.  This is  initially  the  default.   The
  166. header lines look like this:
  167.  
  168.      --------- C:\VBDOS\BFIND.BAS
  169.  
  170. "/EMPTY" says that the -----infile header information is to be  shown  even  if
  171. the file doesn't have any hits in it.  This is initially the default.
  172.  
  173. "/-EMPTY" says to only show the -----infile header information if the file  has
  174. hits.  Initially defaults to "/EMPTY".
  175.  
  176. "/FILTER"  specifies  that  the  program  is  to  replace   with   spaces   all
  177. non-printable  characters  from  the  input   file(s).    See   the   "Defining
  178. Character-Translations" discussion above.  Initially defaults to "/-FILTER".
  179.  
  180. "/-FILTER" says to not bother removing the  nonprintable  characters  from  the
  181. output.  This is initially the default.
  182.  
  183. "/FILTER=filename" specifies that a filter is to be applied and  all  character
  184. replacements   are   in   the   file    "filename".     See    the    "Defining
  185. Character-Translations" discussion above.
  186.  
  187. "/LINES line1-line2" says to restrict the search to lines between line  numbers
  188. line1 and line2 inclusive.  You can have multiple line requests  in  any  order
  189. such as "/LINES 1-10 90-100 30-50".  The routine  skips  all  lines  after  the
  190. largest line number is encountered.  Defaults to "/LINES 1-9999999".
  191.  
  192. "/LINES line1 linect" says to restrict the search to lines beginning with line1
  193. and continuing for a total of linect lines.  So "/LINES 10 20" is actually  the
  194. same as "/LINES 10-29".
  195.  
  196. "/ATTR=attribs" allows you to specify a combination of attributes that you want
  197. considered.  You can specify any combination of R (read-only),  H  (hidden),  S
  198. (system), or A (archive bit).  Precede any character(s)  with  "-"  to  exclude
  199. instead of include.  Unlike with  the  DOS  DIR  command,  the  inclusions  and
  200. exclusions are subject to "OR" conditions; /ATTR=HS will retrieve any file that
  201. is either hidden or a system file or both.   You  can  specify  "/ATTR=ALL"  to
  202. specify that all files are to be processed.  Initially defaults to /ATTR=-H-S-R
  203. (skip hidden, system, or read-only files).
  204.  
  205. "/S" processes files in subdirectories off the specified subdirectory.   /S  is
  206. ignored if a @listfile is provided.  Initially defaults to "/-S".
  207.  
  208. "/W" says to pause with a "Press any key to continue" message after the program
  209. finishes if any hits were found.   Note  that  this  parameter  is  ignored  if
  210. redirection out is being used.
  211.  
  212. "/W0" says to pause afterward whether any hits were  found  or  not.   This  is
  213. initially the default if the program is run  under  Windows.   Note  that  this
  214. parameter is ignored if redirection out is being used.
  215.  
  216. "/-W" says to not pause afterward at all.  This is initially the default if the
  217. program is run under DOS.
  218.  
  219.  
  220. BFIND.DOC                              5                           Apr 28, 1997
  221.  
  222. "/MONO" (or "/-COLOR") does not  try  to  override  screen  colors.   Initially
  223. defaults to "/COLOR".
  224.  
  225. "/COLOR" (or  "/-MONO")  allows  screen  colors  to  be  overridden.   This  is
  226. initially the default.
  227.  
  228. "/Iinitfile" says to read an initialization file with the file name "initfile".
  229. The file specification *must* contain a period.  Initfiles are described in the
  230. BRUCEINI.DOC file.  Initially defaults to "/IBFIND.INI".
  231.  
  232. "/INULL" says to skip loading the initialization file.
  233.  
  234. "/ENV" says to look for %var% occurrences  in  the  command  line  and  try  to
  235. resolve any apparent environmental variable references.  See  BRUCEINI.DOC  for
  236. more information.  This is initially the default.
  237.  
  238. "/-ENV" says to skip resolving apparent %var% occurrences in the command  line.
  239. Initially defaults to "/ENV".
  240.  
  241. "/?" or "/HELP" shows you the syntax for the command.  (Unlike with  the  other
  242. Wayne Software commands, "HELP" is not supported since the program  takes  this
  243. as your search string.)
  244.  
  245. "/?&H" gives you a hexadecimal and decimal conversion table.
  246.  
  247. "search" is described below.
  248.  
  249. "filespec" tells the routine which file or files  are  to  be  processed.   The
  250. specification can include path and wildcards if  desired.   One  thing  I  find
  251. useful  with  wildcards  is  that  is  allows  me  to  create  an  output  that
  252. concatenates all of the input files together with the typical headers (/HEADER)
  253. that separate each portion.  This requires searching for all lines in a file so
  254. you need to use the /V option and look for an improbable string.  For  example,
  255. to concatenate all *.TXT files together as a new file called TEMP.NEW and  have
  256. the little header between each, say this:
  257.  
  258.         BFIND /V "&#$#" *.TXT > TEMP.NEW
  259.  
  260. "@listfile" allows you to have a variety of file specifications saved in a text
  261. file named "listfile".  Each line in  the  file  should  consist  of  one  file
  262. specification, each of which can include a path and wildcards if desired. Blank
  263. lines and lines beginning with semi-colons, colons, or quotes are ignored.   An
  264. example using this is provided at the end of this documentation.
  265.  
  266. ">filename" redirects the output to a text file.   This  automatically  invokes
  267. the /-P option.  This is useful for saving the found lines into  another  file.
  268. For example:
  269.  
  270.         BFIND "Bruce" TEMP.TXT > TEMP2.TXT
  271.  
  272.  
  273.  
  274. BFIND.DOC                              6                           Apr 28, 1997
  275.  
  276. For search, the syntax is:
  277.  
  278.   [ ( ]... search_item [ boolean [ ( ]... search_item [ ) ]...] [ ) ]...
  279.  
  280. where:
  281.  
  282.   ( and )     are used to group items
  283.   search_item is shown below
  284.   boolean     is AND, OR, or XOR (NOT is included with search_item)
  285.  
  286. for search_item, the syntax is:
  287.  
  288.   [ NOT ]  "string" [ column ]
  289.  
  290. where:
  291.  
  292.   NOT         is obvious
  293.   string      the string to search; the quotation marks are typically not
  294.               required unless the string contains a space or a reserved word
  295.               or begins with a slash ("/")
  296.   column      is the column in which the string must be found.
  297.  
  298. So, let's cover some examples:
  299.  
  300.         BFIND "Bugs Bunny" OR "Elmer Fudd" TEST.TXT
  301.  
  302. Quotes are needed around a string if it begins with a slash:
  303.  
  304.         BFIND "/1997" TEST.TXT
  305.  
  306. Finds any lines in the file TEST.TXT containing either "Bugs Bunny"  or  "Elmer
  307. Fudd" in them.
  308.  
  309.         BFIND (Apples or Oranges) AND NOT Pears TEST2.TXT
  310.  
  311. Finds any lines in the file TEST2.TXT  which  contain  the  words  "Apples"  or
  312. "Oranges" in them and ignores any lines  containing  "Pears".   Note  that  the
  313. quotes around the search words are not required unless the words include spaces
  314. or unless they could be confused with some other keywords.  "BFIND  OR  OR  AND
  315. TEST3.TXT" might cause the program to get confused since "OR" and "AND",  which
  316. you want to look for, are also keywords.
  317.  
  318.         BFIND /C "Bugs Bunny" AND Martians TEST.TXT
  319.  
  320. Gives you a total for the number of lines  containing  both  "Bugs  Bunny"  and
  321. "Martians".
  322.  
  323. The search string can include any text characters.  It can also  contain  ASCII
  324. codes, created either using the Alt key in combination with the numeric  keypad
  325. (for example, Alt-228 to  get  a  Sigma  character)  or  else  by  embedding  a
  326. hexadecimal code (in the form &Hxx) or a decimal code (in the form \nnn) in the
  327. text.  These codes are described in the BRUCEHEX.DOC  file.   For  example,  to
  328. find the smiley face character  in  a  file  called  TEST.TXT,  either  of  the
  329. following work:
  330.  
  331.         BFIND "" TEST.TXT
  332.         BFIND \001 TEST.TXT
  333.  
  334. BFIND.DOC                              7                           Apr 28, 1997
  335.  
  336. If you search for more than one word without using a  Boolean  operator,  BFIND
  337. presumes you wanted the words searched with  an  "AND"  Boolean  operator.   So
  338. this:
  339.  
  340.         BFIND Print Form *.TXT
  341.  
  342. is the same thing as saying:
  343.  
  344.         BFIND Print AND Form *.TXT
  345.  
  346. If you wanted to search for the *phrase* "Print Form", you'd have to say:
  347.  
  348.         BFIND "Print Form" *.TXT
  349.  
  350. You can press the Esc key to abort the search early.
  351.  
  352. BFIND, unlike FIND, typically doesn't  require  the  search  string  to  be  in
  353. quotes. As  a  result,  you  can  create  a  text  file  (presume  it's  called
  354. C:\BAT\PHONE.TXT) containing phone numbers or something and then create a batch
  355. file (like PHONE.BAT) that looks like this:
  356.  
  357.         BFIND %1 %2 %3 %4 %5 C:\BAT\PHONE.TXT
  358.  
  359. When you want to find a phone number, you just say "PHONE  name".   This  is  a
  360. little more natural that using FIND which would require that  you  enclose  the
  361. name in quotes.  You can still use the Boolean operators in  BFIND;  the  batch
  362. file above would allow up to five parameters.
  363.  
  364. If you have multiple phone books, use the @listfile option in the  batch  file.
  365. For example, I have four phone files I search; a personal one  (PHONES.TXT),  a
  366. list of e-mail addresses (PHONMAIL.TXT), a list of work-related  phone  numbers
  367. that  are  distributed  to  the  office  (EBBPHONE.TXT),  and  an  office  list
  368. (OBAPHONE.TXT).  My @listfile is called C:\MINE\PHONE.LST  and  contains  these
  369. lines:
  370.  
  371.         c:\mine\phones.txt
  372.         c:\mine\phonmail.txt
  373.         c:\mine\ebbphone.txt
  374.         c:\mine\obaphone.txt
  375.  
  376. My PHONE.BAT file contains this line:
  377.  
  378.         BFIND /I /P /-EMPTY %1 %2 %3 %4 @C:\MINE\PHONE.LST
  379.  
  380.  
  381.  
  382. BFIND.DOC                              8                           Apr 28, 1997
  383.  
  384. Return codes:
  385.  
  386. BFIND returns the following ERRORLEVEL codes:
  387.         0 = no problems, string found
  388.         1 = no problems, string not found
  389.       250 = operation aborted by pressing Escape
  390.       255 = syntax problems, file not found, or /? requested
  391.  
  392.  
  393. Author:
  394.  
  395. This program was written by Bruce Guthrie of Wayne Software.  It  is  free  for
  396. use and  redistribution  provided  relevant  documentation  is  kept  with  the
  397. program, no changes are made to the program or documentation,  and  it  is  not
  398. bundled with commercial programs or charged for separately.  People who need to
  399. bundle it in for-sale packages must  pay  a  $50  registration  fee  to  "Wayne
  400. Software" at the following address.
  401.  
  402. Additional information about this and other  Wayne  Software  programs  can  be
  403. found in the file BRUCE.DOC which should be included in the original ZIP  file.
  404. The recent change history for this and the other programs is  provided  in  the
  405. HISTORY.ymm file which should be in the same ZIP file where "y" is replaced  by
  406. the last digit of the year and "mm" is the two  digit  month  of  the  release;
  407. HISTORY.611 came out in November 1996.  This same naming convention is used  in
  408. naming the ZIP file (BFINDymm.ZIP) that this program was included in.
  409.  
  410. Comments and suggestions can also be sent to:
  411.  
  412.                 Bruce Guthrie
  413.                 Wayne Software
  414.                 113 Sheffield St.
  415.                 Silver Spring, MD 20910
  416.  
  417.                 fax: (301) 588-8986
  418.                 e-mail: bguthrie@nmaa.org
  419.                 http://www.geocities.com/SiliconValley/Lakes/2414
  420.  
  421. Please provide an Internet e-mail address on all correspondence.
  422.  
  423. 
  424.